home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_ddd.idb / usr / freeware / info / ddd.info-4.z / ddd.info-4
Text File  |  2001-10-09  |  51KB  |  1,354 lines
  1. This is ddd.info, produced by makeinfo version 4.0 from ddd.texi.
  2.  
  3. INFO-DIR-SECTION Miscellaneous
  4. START-INFO-DIR-ENTRY
  5. * DDD: (ddd).                     The Data Display Debugger.
  6. END-INFO-DIR-ENTRY
  7.  
  8. DDD is a graphical front-end for GDB and other command-line debuggers.
  9.  
  10. This is the First Edition, 2001-02-01, of `Debugging with DDD' for DDD
  11. Version 3.3.1.
  12.  
  13. Copyright (C) 2001 UniversitΣt Passau
  14. Lehrstuhl fⁿr Software-Systeme
  15. Innstra▀e 33
  16. D-94032 Passau
  17. GERMANY
  18.  
  19. Distributed by
  20. Free Software Foundation, Inc.
  21. 59 Temple Place - Suite 330
  22. Boston, MA 02111-1307
  23. USA
  24.  
  25. DDD and this manual are available via the DDD WWW page
  26. (http://www.gnu.org/software/ddd/).
  27.  
  28.    Permission is granted to copy, distribute and/or modify this document
  29. under the terms of the GNU Free Documentation License, Version 1.1 or
  30. any later version published by the Free Software Foundation; with no
  31. Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.  A
  32. copy of the license is included in the section entitled "GNU Free
  33. Documentation License".
  34.  
  35.    Send questions, comments, suggestions, etc. to <ddd@gnu.org>.
  36. Send bug reports to <bug-ddd@gnu.org>.
  37. 
  38. File: ddd.info,  Node: Help Helpers,  Prev: Tip of the day,  Up: Customizing Help
  39.  
  40. Help Helpers
  41. ............
  42.  
  43.    DDD relies on a number of external commands, specified via `Edit =>
  44. Preferences => Helpers'.
  45.  
  46.    To uncompress help texts, you can define a `Uncompress' command:
  47.  
  48.  - Resource: uncompressCommand (class UncompressCommand)
  49.      The command to uncompress the built-in DDD manual, the DDD
  50.      license, and the DDD news.  Takes a compressed text from standard
  51.      input and writes the uncompressed text to standard output.  The
  52.      default value is `gzip -d -c'; typical values include `zcat' and
  53.      `gunzip -c'.
  54.  
  55.    To view WWW pages, you can define a `Web Browser' command:
  56.  
  57.  - Resource: wwwCommand (class WWWCommand)
  58.      The command to invoke a WWW browser.  The string `@URL@' is
  59.      replaced by the URL to open.  Default is to try a running Netscape
  60.      first (trying `mozilla', then `netscape'), then `$WWWBROWSER',
  61.      then to invoke a new Netscape process, then to let a running Emacs
  62.      or XEmacs do the job (via `gnudoit'), then to invoke Mosaic, then
  63.      to invoke Lynx in an xterm.
  64.  
  65.      To specify `netscape-6.0' as browser, use the setting:
  66.  
  67.           Ddd*wwwCommand: \
  68.                netscape-6.0 -remote 'openURL(@URL@)' \
  69.             || netscape-6.0 '@URL@'
  70.  
  71.      This command first tries to connect to a running `netscape-6.0'
  72.      browser; if this fails, it starts a new `netscape-6.0' process.
  73.  
  74.    This is the default WWW Page shown by `Help => DDD WWW Page':
  75.  
  76.  - Resource: wwwPage (class WWWPage)
  77.      The DDD WWW page.  Value: `http://www.gnu.org/software/ddd/'
  78.  
  79. 
  80. File: ddd.info,  Node: Customizing Undo,  Next: Customizing Windows,  Prev: Customizing Help,  Up: Customizing
  81.  
  82. Customizing Undo
  83. ----------------
  84.  
  85.    DDD Undo can be customized in various ways.
  86.  
  87.    To set a maximum size for the undo buffer, set `Edit => Preferences
  88. => General => Undo Buffer Size'.
  89.  
  90.    This is related to the `maxUndoSize' resource:
  91.  
  92.  - Resource: maxUndoSize (class MaxUndoSize)
  93.      The maximum memory usage (in bytes) of the undo buffer.  Useful for
  94.      limiting DDD memory usage.  A negative value means to place no
  95.      limit.  Default is `2000000', or 2000 kBytes.
  96.  
  97.    You can also limit the number of entries in the undo buffer,
  98. regardless of size (*note Customizing::):
  99.  
  100.  - Resource: maxUndoDepth (class MaxUndoDepth)
  101.      The maximum number of entries in the undo buffer.  This limits the
  102.      number of actions that can be undone, and the number of states that
  103.      can be shown in historic mode.  Useful for limiting DDD memory
  104.      usage.  A negative value (default) means to place no limit.
  105.  
  106.    To clear the undo buffer at any time, thus reducing memory usage, use
  107. `Edit => Preferences => General => Clear Undo Buffer'
  108.  
  109. 
  110. File: ddd.info,  Node: Customizing Windows,  Next: Debugger Settings,  Prev: Customizing Undo,  Up: Customizing
  111.  
  112. Customizing the DDD Windows
  113. ---------------------------
  114.  
  115.    You can customize the DDD Windows in various ways.
  116.  
  117. * Menu:
  118.  
  119. * Splash Screen::               Turning off the splash screen.
  120. * Window Layout::               Re-arranging windows.
  121. * Customizing Fonts::           Using alternate fonts.
  122. * Toggling Windows::            Turning off windows.
  123. * Text Fields::                 Popdown histories.
  124. * Icons::                       Iconifying DDD windows.
  125. * Adding Buttons::              Create your own button set.
  126. * More Customizations::
  127.  
  128. 
  129. File: ddd.info,  Node: Splash Screen,  Next: Window Layout,  Up: Customizing Windows
  130.  
  131. Splash Screen
  132. .............
  133.  
  134.    You can turn off the DDD splash screen shown upon startup.  Just
  135. select `Edit => Preferences => Startup DDD Splash Screen'.
  136.  
  137.    The value applies only to the next DDD invocation.
  138.  
  139.    This setting is related to the following resource:
  140.  
  141.  - Resource: splashScreen (class SplashScreen)
  142.      If `on' (default), show a DDD splash screen upon start-up.
  143.  
  144.    You can also customize the appearance of the splash screen (*note
  145. Customizing::):
  146.  
  147.  - Resource: splashScreenColorKey (class ColorKey)
  148.      The color key to use for the DDD splash screen.  Possible values
  149.      include:
  150.  
  151.         * `c' (default) for a color visual,
  152.  
  153.         * `g' for a multi-level greyscale visual,
  154.  
  155.         * `g4' for a 4-level greyscale visual, and
  156.  
  157.         * `m' for a dithered monochrome visual.
  158.  
  159.         * `best' chooses the best visual available for your display.
  160.  
  161.      Please note: if DDD runs on a monochrome display, or if DDD was
  162.      compiled without the XPM library, only the monochrome version
  163.      (`m') can be shown.
  164.  
  165. 
  166. File: ddd.info,  Node: Window Layout,  Next: Customizing Fonts,  Prev: Splash Screen,  Up: Customizing Windows
  167.  
  168. Window Layout
  169. .............
  170.  
  171.    By default, DDD stacks commands, source, and data in one single
  172. top-level window.  To have separate top-level windows for source, data,
  173. and debugger console, set `Edit => Preferences => Startup => Window
  174. Layout => Separate Windows'.
  175.  
  176.    Here are the related DDD resources:
  177.  
  178.  - Resource: separateDataWindow (class Separate)
  179.      If `on', the data window and the debugger console are realized in
  180.      different top-level windows.  If `off' (default), the data window
  181.      is attached to the debugger console.
  182.  
  183.  - Resource: separateSourceWindow (class Separate)
  184.      If `on', the source window and the debugger console are realized in
  185.      different top-level windows.  If `off' (default), the source window
  186.      is attached to the debugger console.
  187.  
  188.    By default, the DDD tool bars are located on top of the window.  If
  189. you prefer the tool bar being located at the bottom, as in DDD 2.x and
  190. earlier, set `Edit => Preferences => Startup => Tool Bar Appearance =>
  191. Bottom'.
  192.  
  193.    This is related to the `toolbarsAtBottom' resource:
  194.  
  195.  - Resource: toolbarsAtBottom (class ToolbarsAtBottom)
  196.      Whether source and data tool bars should be placed above source and
  197.      data, respectively (`off', default), or below, as in DDD 2.x
  198.      (`on').
  199.  
  200.    The bottom setting is only supported for separate tool bars--that is,
  201. you must either choose separate windows or configure the tool bar to
  202. have neither images nor captions (*note Customizing the Tool Bar::).
  203.  
  204.    If you use stacked windows, you can choose whether there should be
  205. one tool bar or two tool bars.  By default, DDD uses two tool bars if
  206. you use separate windows and disable captions and images, but you can
  207. also explicitly change the setting via this resource:
  208.  
  209.  - Resource: commonToolBar (class ToolBar)
  210.      Whether the tool bar buttons should be shown in one common tool
  211.      bar at the top of the common DDD window (`on', default), or
  212.      whether they should be placed in two separate tool bars, one for
  213.      data, and one for source operations, as in DDD 2.x (`off').
  214.  
  215.    You can also change the location of the _status line_ (*note
  216. Customizing::):
  217.  
  218.  - Resource: statusAtBottom (class StatusAtBottom)
  219.      If `on' (default), the status line is placed at the bottom of the
  220.      DDD source window.  If `off', the status line is placed at the top
  221.      of the DDD source window (as in DDD 1.x).
  222.  
  223.    *Note Options::, for options to set these resources upon DDD
  224. invocation.
  225.  
  226. 
  227. File: ddd.info,  Node: Customizing Fonts,  Next: Toggling Windows,  Prev: Window Layout,  Up: Customizing Windows
  228.  
  229. Customizing Fonts
  230. .................
  231.  
  232.    You can configure the basic DDD fonts at run-time.  Each font is
  233. specified using two members:
  234.  
  235.    * The "font family" is an X font specifications, where the initial
  236.      `FOUNDRY-' specification may be omitted, as well as any
  237.      specification after FAMILY.  Thus, a pair `FAMILY-WEIGHT' usually
  238.      suffices.
  239.  
  240.    * The "font size" is given as (resolution-independent) 1/10 points.
  241.  
  242.    To specify fonts, select `Edit => Preferences => Fonts'.
  243.  
  244.    The `Browse' button opens a font selection program, where you can
  245. select fonts and attributes interactively.  Clicking `quit' or `select'
  246. in the font selector causes all non-default values to be transferred to
  247. the DDD font preferences panel.
  248.  
  249.    The following fonts can be set using the preferences panel:
  250.  
  251. `Default Font'
  252.      The default DDD font to use for labels, menus, and buttons.
  253.      Default is `helvetica-bold'.
  254.  
  255. `Variable Width'
  256.      The variable width DDD font to use for help texts and messages.
  257.      Default is `helvetica-medium'.
  258.  
  259. `Fixed Width'
  260.      The fixed width DDD font to use for source code, the debugger
  261.      console, text fields, and the execution window.  Default is
  262.      `lucidatypewriter-medium'.
  263.  
  264. `Data'
  265.      The DDD font to use for data displays.  Default is
  266.      `lucidatypewriter-medium'.
  267.  
  268.    Changes in this panel will not take effect immediately.  Instead, you
  269. can
  270.  
  271.    * save options (using `Edit => Save Options') to make the change
  272.      effective for future DDD sessions,
  273.  
  274.    * or restart DDD (using `File => Restart DDD') to make it effective
  275.      for the restarted DDD session.
  276.  
  277.    After having made changes in the panel, DDD will automatically offer
  278. you to restart itself, such that you can see the changes taking effect.
  279. Note that even after restarting, you still must save options to make
  280. the changes permanent.
  281.  
  282.    The `Reset' button restores the most recently saved preferences.
  283.  
  284.    Here are the resources related to font specifications:
  285.  
  286.  - Resource: defaultFont (class Font)
  287.      The default DDD font to use for labels, menus, buttons, etc.  The
  288.      font is specified as an X font spec, where the initial FOUNDRY
  289.      specification may be omitted, as well as any specification after
  290.      FAMILY.
  291.  
  292.      Default value is `helvetica-bold'.
  293.  
  294.      To set the default DDD font to, say, `helvetica medium', insert a
  295.      line
  296.  
  297.           Ddd*defaultFont: helvetica-medium
  298.  
  299.      in your `~/.ddd/init' file.
  300.  
  301.  - Resource: defaultFontSize (class FontSize)
  302.      The size of the default DDD font, in 1/10 points.  This resource
  303.      overrides any font size specification in the `defaultFont' resource
  304.      (see above).  The default value is `120' for a 12.0 point font.
  305.  
  306.  - Resource: variableWidthFont (class Font)
  307.      The variable width DDD font to use for help texts and messages.
  308.      The font is specified as an X font spec, where the initial FOUNDRY
  309.      specification may be omitted, as well as any specification after
  310.      FAMILY.
  311.  
  312.      Default value is `helvetica-medium-r'.
  313.  
  314.      To set the variable width DDD font family to, say, `times', insert
  315.      a line
  316.  
  317.           Ddd*fixedWidthFont: times-medium
  318.  
  319.      in your `~/.ddd/init' file.
  320.  
  321.  - Resource: variableWidthFontSize (class FontSize)
  322.      The size of the variable width DDD font, in 1/10 points.  This
  323.      resource overrides any font size specification in the
  324.      `variableWidthFont' resource (see above).  The default value is
  325.      `120' for a 12.0 point font.
  326.  
  327.  - Resource: fixedWidthFont (class Font)
  328.      The fixed width DDD font to use for source code, the debugger
  329.      console, text fields, and the execution window.  The font is
  330.      specified as an X font spec, where the initial FOUNDRY
  331.      specification may be omitted, as well as any specification after
  332.      FAMILY.
  333.  
  334.      Default value is `lucidatypewriter-medium'.
  335.  
  336.      To set the fixed width DDD font family to, say, `courier', insert
  337.      a line
  338.  
  339.           Ddd*fixedWidthFont: courier-medium
  340.  
  341.      in your `~/.ddd/init' file.
  342.  
  343.  - Resource: fixedWidthFontSize (class FontSize)
  344.      The size of the fixed width DDD font, in 1/10 points.  This
  345.      resource overrides any font size specification in the
  346.      `fixedWidthFont' resource (see above).  The default value is `120'
  347.      for a 12.0 point font.
  348.  
  349.  - Resource: dataFont (class Font)
  350.      The fixed width DDD font to use data displays.  The font is
  351.      specified as an X font spec, where the initial FOUNDRY
  352.      specification may be omitted, as well as any specification after
  353.      FAMILY.
  354.  
  355.      Default value is `lucidatypewriter-medium'.
  356.  
  357.      To set the DDD data font family to, say, `courier', insert a line
  358.  
  359.           Ddd*dataFont: courier-medium
  360.  
  361.      in your `~/.ddd/init' file.
  362.  
  363.  - Resource: dataFontSize (class FontSize)
  364.      The size of the DDD data font, in 1/10 points.  This resource
  365.      overrides any font size specification in the `dataFont' resource
  366.      (see above).  The default value is `120' for a 12.0 point font.
  367.  
  368.    As all font size resources have the same class (and by default the
  369. same value), you can easily change the default DDD font size to, say,
  370. 9.0 points by inserting a line
  371.  
  372.      Ddd*FontSize: 90
  373.  
  374. in your `~/.ddd/init' file.
  375.  
  376.    Here's how to specify the command to select fonts:
  377.  
  378.  - Resource: fontSelectCommand (class FontSelectCommand)
  379.      A command to select from a list of fonts.  The string `@FONT@' is
  380.      replaced by the current DDD default font; the string `@TYPE@' is
  381.      replaced by a symbolic name of the DDD font to edit.  The program
  382.      must either place the name of the selected font in the `PRIMARY'
  383.      selection or print the selected font on standard output.  A
  384.      typical value is:
  385.           Ddd*fontSelectCommand: xfontsel -print
  386.  
  387.    *Note Options::, for options to set these resources upon DDD
  388. invocation.
  389.  
  390. 
  391. File: ddd.info,  Node: Toggling Windows,  Next: Text Fields,  Prev: Customizing Fonts,  Up: Customizing Windows
  392.  
  393. Toggling Windows
  394. ................
  395.  
  396.    In the default stacked window setting, you can turn the individual
  397. DDD windows on and off by toggling the respective items in the `View'
  398. menu (*note View Menu::).  When using separate windows (*note Window
  399. Layout::), you can close the individual windows via `File => Close' or
  400. by closing them via your window manager.
  401.  
  402.    Whether windows are opened or closed when starting DDD is controlled
  403. by the following resources, immediately tied to the `View' menu items:
  404.  
  405.  - Resource: openDataWindow (class Window)
  406.      If `off' (default), the data window is closed upon start-up.
  407.  
  408.  - Resource: openDebuggerConsole (class Window)
  409.      If `off', the debugger console is closed upon start-up.
  410.  
  411.  - Resource: openSourceWindow (class Window)
  412.      If `off', the source window is closed upon start-up.
  413.  
  414.    *Note Options::, for options to set these resources upon DDD
  415. invocation.
  416.  
  417. 
  418. File: ddd.info,  Node: Text Fields,  Next: Icons,  Prev: Toggling Windows,  Up: Customizing Windows
  419.  
  420. Text Fields
  421. ...........
  422.  
  423.    The DDD text fields can be customized using the following resources:
  424.  
  425.  - Resource: popdownHistorySize (class HistorySize)
  426.      The maximum number of items to display in pop-down value
  427.      histories.  A value of `0' (default) means an unlimited number of
  428.      values.
  429.  
  430.  - Resource: sortPopdownHistory (class SortPopdownHistory)
  431.      If `on' (default), items in the pop-down value histories are sorted
  432.      alphabetically.  If `off', most recently used values will appear at
  433.      the top.
  434.  
  435. 
  436. File: ddd.info,  Node: Icons,  Next: Adding Buttons,  Prev: Text Fields,  Up: Customizing Windows
  437.  
  438. Icons
  439. .....
  440.  
  441.    If you frequently switch between DDD and other multi-window
  442. applications, you may like to set `Edit => Preferences => General =>
  443. Iconify all windows at once'.  This way, all DDD windows are iconified
  444. and deiconified as a group.
  445.  
  446.    This is tied to the following resource:
  447.  
  448.  - Resource: groupIconify (class GroupIconify)
  449.      If this is `on', (un)iconifying any DDD window causes all other
  450.      DDD windows to (un)iconify as well.  Default is `off', meaning
  451.      that each DDD window can be iconified on its own.
  452.  
  453.    If you want to keep DDD off your desktop during a longer
  454. computation, you may like to set `Edit => Preferences => General =>
  455. Uniconify when ready'.  This way, you can iconify DDD while it is busy
  456. on a command (e.g. running a program); DDD will automatically pop up
  457. again after becoming ready (e.g. after the debugged program has stopped
  458. at a breakpoint).  *Note Program Stop::, for a discussion.
  459.  
  460.    Here is the related resource:
  461.  
  462.  - Resource: uniconifyWhenReady (class UniconifyWhenReady)
  463.      If this is `on' (default), the DDD windows are uniconified
  464.      automatically whenever GDB becomes ready.  This way, you can
  465.      iconify DDD during some longer operation and have it uniconify
  466.      itself as soon as the program stops.  Setting this to `off' leaves
  467.      the DDD windows iconified.
  468.  
  469. 
  470. File: ddd.info,  Node: Adding Buttons,  Next: More Customizations,  Prev: Icons,  Up: Customizing Windows
  471.  
  472. Adding Buttons
  473. ..............
  474.  
  475.    You can extend DDD with new buttons.  *Note Defining Buttons::, for
  476. details.
  477.  
  478. 
  479. File: ddd.info,  Node: More Customizations,  Prev: Adding Buttons,  Up: Customizing Windows
  480.  
  481. More Customizations
  482. ...................
  483.  
  484.    You can change just about any label, color, keyboard mapping, etc.
  485. by changing resources from the `Ddd' application defaults file which
  486. comes with the DDD source distribution.  Here's how it works:
  487.  
  488.    * Identify the appropriate resource in the `Ddd' file.
  489.  
  490.    * Copy the resource line to your `~/.ddd/init' file and change it at
  491.      will.
  492.  
  493.    *Note Application Defaults::, for details on the application-defaults
  494. file.
  495.  
  496. 
  497. File: ddd.info,  Node: Debugger Settings,  Prev: Customizing Windows,  Up: Customizing
  498.  
  499. Debugger Settings
  500. -----------------
  501.  
  502.    For most inferior debuggers, you can change their internal settings
  503. using `Edit => Settings'.  Using the settings editor, you can determine
  504. whether C++ names are to be demangled, how many array elements are to
  505. print, and so on.
  506.  
  507.    The capabilities of the settings editor depend on the capabilities of
  508. your inferior debugger.  Clicking on `?' gives an an explanation on the
  509. specific item; the GDB documentation gives more details.
  510.  
  511.    Use `Edit => Undo' to undo changes.  Clicking on `Reset' restores
  512. the most recently saved settings.
  513.  
  514.    Some debugger settings are insensitive and cannot be changed, because
  515. doing so would endanger DDD operation.  See the `gdbInitCommands' and
  516. `dbxInitCommands' resources for details.
  517.  
  518.    All debugger settings (except source and object paths) are saved with
  519. DDD options.
  520.  
  521. 
  522. File: ddd.info,  Node: Navigating,  Next: Stopping,  Prev: Windows,  Up: Top
  523.  
  524. Navigating through the Code
  525. ***************************
  526.  
  527.    This chapter discusses how to access code from within DDD.
  528.  
  529. * Menu:
  530.  
  531. * Compiling for Debugging::     Always use `-g' to compile.
  532. * Opening Files::               How to open a program for debugging.
  533. * Looking up Items::            Searching files and functions.
  534. * Customizing Source::          Arranging the source window.
  535.  
  536. 
  537. File: ddd.info,  Node: Compiling for Debugging,  Next: Opening Files,  Up: Navigating
  538.  
  539. Compiling for Debugging
  540. =======================
  541.  
  542.    In order to debug a program effectively, you need to generate
  543. debugging information when you compile it.  This debugging information
  544. is stored in the object file; it describes the data type of each
  545. variable or function and the correspondence between source line numbers
  546. and addresses in the executable code.(1)
  547.  
  548.    To request debugging information, specify the `-g' option when you
  549. run the compiler.
  550.  
  551.    Many C compilers are unable to handle the `-g' and `-O' options
  552. together.  Using those compilers, you cannot generate optimized
  553. executables containing debugging information.
  554.  
  555.    GCC, the GNU C compiler, supports `-g' with or without `-O', making
  556. it possible to debug optimized code.  We recommend that you _always_
  557. use `-g' whenever you compile a program.  You may think your program is
  558. correct, but there is no sense in pushing your luck.
  559.  
  560.    When you debug a program compiled with `-g -O', remember that the
  561. optimizer is rearranging your code; the debugger shows you what is
  562. really there.  Do not be too surprised when the execution path does not
  563. exactly match your source file!  An extreme example: if you define a
  564. variable, but never use it, DDD never sees that variable--because the
  565. compiler optimizes it out of existence.
  566.  
  567.    ---------- Footnotes ----------
  568.  
  569.    (1) If you use DDD to debug Perl or Python scripts, then this
  570. section does not apply.
  571.  
  572. 
  573. File: ddd.info,  Node: Opening Files,  Next: Looking up Items,  Prev: Compiling for Debugging,  Up: Navigating
  574.  
  575. Opening Files
  576. =============
  577.  
  578.    If you did not invoke DDD specifying a program to be debugged, you
  579. can use the `File' menu to open programs, core dumps and sources.
  580.  
  581. * Menu:
  582.  
  583. * Opening Programs::            How to open a program for debugging.
  584. * Opening Core Dumps::          Analyze a previous crash.
  585. * Opening Source Files::        Open a source file of the program.
  586. * Filtering Files::             DDD only lists matching files.
  587.  
  588. 
  589. File: ddd.info,  Node: Opening Programs,  Next: Opening Core Dumps,  Up: Opening Files
  590.  
  591. Opening Programs
  592. ----------------
  593.  
  594.    To open a program to be debugged, select `File => Open Program'.(1)
  595. Click on `Open' to open the program
  596.  
  597.    In JDB, select `File => Open Class' instead.  This gives you a list
  598. of available classes to choose from.
  599.  
  600.    To re-open a recently debugged program or class, select `File =>
  601. Open Recent' and choose a program or class from the list.
  602.  
  603.    If no sources are found, *Note Source Path::, for specifying source
  604. directories.
  605.  
  606.    ---------- Footnotes ----------
  607.  
  608.    (1) With XDB and some DBX variants, the debugged program must be
  609. specified upon invocation and cannot be changed at run time.
  610.  
  611. 
  612. File: ddd.info,  Node: Opening Core Dumps,  Next: Opening Source Files,  Prev: Opening Programs,  Up: Opening Files
  613.  
  614. Opening Core Dumps
  615. ------------------
  616.  
  617.    If a previous run of the program has crashed and you want to find out
  618. why, you can have DDD examine its "core dump".(1)
  619.  
  620.    To open a core dump for the program, select `File => Open Core
  621. Dump'.  Click on `Open' to open the core dump.
  622.  
  623.    Before `Open Core Dump', you should first use `File => Open Program'
  624. to specify the program that generated the core dump and to load its
  625. symbol table.
  626.  
  627.    ---------- Footnotes ----------
  628.  
  629.    (1) JDB, PYDB, and Perl do not support core dumps.
  630.  
  631. 
  632. File: ddd.info,  Node: Opening Source Files,  Next: Filtering Files,  Prev: Opening Core Dumps,  Up: Opening Files
  633.  
  634. Opening Source Files
  635. --------------------
  636.  
  637.    To open a source file of the debugged program, select `File => Open
  638. Source'.
  639.  
  640.    * Using GDB, this gives you a list of the sources used for compiling
  641.      your program.
  642.  
  643.    * Using other inferior debuggers, this gives you a list of accessible
  644.      source files, which may or may not be related to your program.
  645.  
  646.    Click on `Open' to open the source file.  *Note Source Path::, if no
  647. sources are found.
  648.  
  649. 
  650. File: ddd.info,  Node: Filtering Files,  Prev: Opening Source Files,  Up: Opening Files
  651.  
  652. Filtering Files
  653. ---------------
  654.  
  655.    When presenting files to be opened, DDD by default filters files
  656. when opening execution files, core dumps, or source files, such that the
  657. selection shows only suitable files.  This requires that DDD opens each
  658. file, which may take time.  *Note Customizing File Filtering::, if you
  659. want to turn off this feature.
  660.  
  661. 
  662. File: ddd.info,  Node: Looking up Items,  Next: Customizing Source,  Prev: Opening Files,  Up: Navigating
  663.  
  664. Looking up Items
  665. ================
  666.  
  667.    As soon as the source of the debugged program is available, the
  668. _source window_ displays its current source text.  (*note Source
  669. Path::, if a source text cannot be found.)
  670.  
  671.    In the source window, you can lookup and examine function and
  672. variable definitions as well as search for arbitrary occurrences in the
  673. source text.
  674.  
  675. * Menu:
  676.  
  677. * Looking up Definitions::      Jump towards a specific item.
  678. * Textual Search::              Search within the current source.
  679. * Looking up Previous Locations::  Navigate back and forth.
  680. * Source Path::                 Make DDD know where to search.
  681.  
  682. 
  683. File: ddd.info,  Node: Looking up Definitions,  Next: Textual Search,  Up: Looking up Items
  684.  
  685. Looking up Definitions
  686. ----------------------
  687.  
  688.    If you wish to lookup a specific function or variable definition
  689. whose name is visible in the source text, click with _mouse button 1_ on
  690. the function or variable name.  The name is copied to the argument
  691. field.  Change the name if desired and click on the `Lookup' button to
  692. find its definition.
  693.  
  694.    As a faster alternative, you can simply press _mouse button 3_ on the
  695. function name and select the `Lookup' item from the source popup menu.
  696.  
  697.    As an even faster alternative, you can also double-click on a
  698. function call (an identifier followed by a `(' character) to lookup the
  699. function definition.
  700.  
  701.    If a source file is not found, *Note Source Path::, for specifying
  702. source directories.
  703.  
  704. 
  705. File: ddd.info,  Node: Textual Search,  Next: Looking up Previous Locations,  Prev: Looking up Definitions,  Up: Looking up Items
  706.  
  707. Textual Search
  708. --------------
  709.  
  710.    If the item you wish to search is visible in the source text, click
  711. with _mouse button 1_ on it.  The identifier is copied to the argument
  712. field.  Click on the `Find >>' button to find following occurrences and
  713. on `Find >> => Find << ()' to find previous occurrences.
  714.  
  715.    By default, DDD finds only complete words.  To search for arbitrary
  716. substrings, change the value of the `Source => Find Words Only' option.
  717.  
  718. 
  719. File: ddd.info,  Node: Looking up Previous Locations,  Next: Source Path,  Prev: Textual Search,  Up: Looking up Items
  720.  
  721. Looking up Previous Locations
  722. -----------------------------
  723.  
  724.    After looking up a location, use `Edit => Undo' (or the `Undo'
  725. button on the command tool) to go back to the original locations.
  726. `Edit => Redo' brings you back again to the location you looked for.
  727.  
  728. 
  729. File: ddd.info,  Node: Source Path,  Prev: Looking up Previous Locations,  Up: Looking up Items
  730.  
  731. Specifying Source Directories
  732. -----------------------------
  733.  
  734.    Executable programs sometimes do not record the directories of the
  735. source files from which they were compiled, just the names.  Even when
  736. they do, the directories could be moved between the compilation and your
  737. debugging session.
  738.  
  739.    Here's how GDB accesses source files; other inferior debuggers have
  740. similar methods.
  741.  
  742.    GDB has a list of directories to search for source files; this is
  743. called the "source path".  Each time GDB wants a source file, it tries
  744. all the directories in the list, in the order they are present in the
  745. list, until it finds a file with the desired name.  Note that the
  746. executable search path is _not_ used for this purpose.  Neither is the
  747. current working directory, unless it happens to be in the source path.
  748.  
  749.    If GDB cannot find a source file in the source path, and the object
  750. program records a directory, GDB tries that directory too.  If the
  751. source path is empty, and there is no record of the compilation
  752. directory, GDB looks in the current directory as a last resort.
  753.  
  754.    To specify a source path for your inferior debugger, use `Edit =>
  755. Debugger Settings' (*note Debugger Settings:: and search for
  756. appropriate entries (in GDB, this is `Search path for source files').
  757.  
  758.    If `Debugger Settings' has no suitable entry, you can also specify a
  759. source path for the inferior debugger when invoking DDD.  *Note
  760. Inferior Debugger Options::, for details.
  761.  
  762.    When using JDB, you can set the `CLASSPATH' environment variable to
  763. specify directories where JDB (and DDD) should search for classes.
  764.  
  765.    If DDD does not find a source file for any reason, check the
  766. following issues:
  767.  
  768.    * In order to debug a program effectively, you need to generate
  769.      debugging information when you compile it.  Without debugging
  770.      information, the inferior debugger will be unable to locate the
  771.      source code. To request debugging information, specify the `-g'
  772.      option when you run the compiler.  *Note Compiling for
  773.      Debugging::, for details.
  774.  
  775.    * You may need to tell your inferior debugger where the source code
  776.      files are.  *Note Source Path::, for details.
  777.  
  778.      Using GDB, you can also create a local `.gdbinit' file that
  779.      contains a line `directory PATH'.  Here, PATH is a colon-separated
  780.      list of source paths.
  781.  
  782. 
  783. File: ddd.info,  Node: Customizing Source,  Prev: Looking up Items,  Up: Navigating
  784.  
  785. Customizing the Source Window
  786. =============================
  787.  
  788.    The source window can be customized in a number of ways, most of them
  789. accessed via `Edit => Preferences => Source'.
  790.  
  791. * Menu:
  792.  
  793. * Customizing Glyphs::
  794. * Customizing Searching::
  795. * Customizing Source Appearance::
  796. * Customizing Source Scrolling::
  797. * Customizing Source Lookup::
  798. * Customizing File Filtering::
  799.  
  800. 
  801. File: ddd.info,  Node: Customizing Glyphs,  Next: Customizing Searching,  Up: Customizing Source
  802.  
  803. Customizing Glyphs
  804. ------------------
  805.  
  806.    In the source text, the current execution position and breakpoints
  807. are indicated by symbols ("glyphs").  As an alternative, DDD can also
  808. indicate these positions using text characters.  If you wish to disable
  809. glyphs, set `Edit => Preferences => Source => Show Position and
  810. Breakpoints => as Text Characters' option.  This also makes DDD run
  811. slightly faster, especially when scrolling.
  812.  
  813.    This setting is tied to this resource:
  814.  
  815.  - Resource: displayGlyphs (class DisplayGlyphs)
  816.      If this is `on', the current execution position and breakpoints are
  817.      displayed as glyphs; otherwise, they are shown through characters
  818.      in the text.  The default is `on'.  *Note Options::, for the
  819.      `--glyphs' and `--no-glyphs' options.
  820.  
  821.    You can further control glyphs using the following resources:
  822.  
  823.  - Resource: cacheGlyphImages (class CacheMachineCode)
  824.      Whether to cache (share) glyph images (`on') or not (`off').
  825.      Caching glyph images requires less X resources, but has been
  826.      reported to fail with OSF/Motif 2.1 on XFree86 servers.  Default
  827.      is `off' for OSF/Motif 2.1 or later on GNU/Linux machines, and `on'
  828.      otherwise.
  829.  
  830.  - Resource: glyphUpdateDelay (class GlyphUpdateDelay)
  831.      A delay (in ms) that says how much time to wait before updating
  832.      glyphs while scrolling the source text.  A small value results in
  833.      glyphs being scrolled with the text, a large value disables glyphs
  834.      while scrolling and makes scrolling faster.  Default: `10'.
  835.  
  836.  - Resource: maxGlyphs (class MaxGlyphs)
  837.      The maximum number of glyphs to be displayed (default: `10').
  838.      Raising this value causes more glyphs to be allocated, possibly
  839.      wasting resources that are never needed.
  840.  
  841. 
  842. File: ddd.info,  Node: Customizing Searching,  Next: Customizing Source Appearance,  Prev: Customizing Glyphs,  Up: Customizing Source
  843.  
  844. Customizing Searching
  845. ---------------------
  846.  
  847.    Searching in the source text (*note Textual Search::) is controlled
  848. by these resources, changed via the `Source' menu:
  849.  
  850.  - Resource: findCaseSensitive (class FindCaseSensitive)
  851.      If this is `on' (default), the `Find' commands are case-sensitive.
  852.      Otherwise, occurrences are found regardless of case.
  853.  
  854.  - Resource: findWordsOnly (class FindWordsOnly)
  855.      If this is `on' (default), the `Find' commands find complete words
  856.      only.  Otherwise, arbitrary occurrences are found.
  857.  
  858. 
  859. File: ddd.info,  Node: Customizing Source Appearance,  Next: Customizing Source Scrolling,  Prev: Customizing Searching,  Up: Customizing Source
  860.  
  861. Customizing Source Appearance
  862. -----------------------------
  863.  
  864.    You can have DDD show line numbers within the source window.  Use
  865. `Edit => Preferences => Source => Display Source Line Numbers'.
  866.  
  867.  - Resource: displayLineNumbers (class DisplayLineNumbers)
  868.      If this is `on', lines in the source text are prefixed with their
  869.      respective line number.  The default is `off'.
  870.  
  871.    You can instruct DDD to indent the source code, leaving more room
  872. for breakpoints and execution glyphs.  This is done using the `Edit =>
  873. Preferences => Source => Source indentation' slider.  The default value
  874. is `0' for no indentation at all.
  875.  
  876.  - Resource: indentSource (class Indent)
  877.      The number of columns to indent the source code, such that there is
  878.      enough place to display breakpoint locations.  Default: `0'.
  879.  
  880.    By default, DDD uses a minimum indentation for script languages.
  881.  
  882.  - Resource: indentScript (class Indent)
  883.      The minimum indentation for script languages, such as Perl and
  884.      Python.  Default: `4'.
  885.  
  886.    The maximum width of line numbers is controlled by this resource.
  887.  
  888.  - Resource: lineNumberWidth (class LineNumberWidth)
  889.      The number of columns to use for line numbers (if displaying line
  890.      numbers is enabled).  Line numbers wider than this value extend
  891.      into the breakpoint space.  Default: `4'.
  892.  
  893.    If your source code uses a tab width different from `8' (the
  894. default), you can set an alternate width using the `Edit => Preferences
  895. => Source => Tab width' slider.
  896.  
  897.  - Resource: tabWidth (class TabWidth)
  898.      The tab width used in the source window (default: `8')
  899.  
  900. 
  901. File: ddd.info,  Node: Customizing Source Scrolling,  Next: Customizing Source Lookup,  Prev: Customizing Source Appearance,  Up: Customizing Source
  902.  
  903. Customizing Source Scrolling
  904. ----------------------------
  905.  
  906.    These resources control when the source window is scrolled:
  907.  
  908.  - Resource: linesAboveCursor (class LinesAboveCursor)
  909.      The minimum number of lines to show before the current location.
  910.      Default is `2'.
  911.  
  912.  - Resource: linesBelowCursor (class LinesBelowCursor)
  913.      The minimum number of lines to show after the current location.
  914.      Default is `3'.
  915.  
  916. 
  917. File: ddd.info,  Node: Customizing Source Lookup,  Next: Customizing File Filtering,  Prev: Customizing Source Scrolling,  Up: Customizing Source
  918.  
  919. Customizing Source Lookup
  920. -------------------------
  921.  
  922.    Some DBX and XDB variants do not properly handle paths in source file
  923. specifications.  If you want the inferior debugger to refer to source
  924. locations by source base names only, unset the `Edit => Preferences =>
  925. Source => Refer to Program Sources by full path name' option.
  926.  
  927.    This is related to the following resource:
  928.  
  929.  - Resource: useSourcePath (class UseSourcePath)
  930.      If this is `off' (default), the inferior debugger refers to source
  931.      code locations only by their base names.  If this is `on'
  932.      (default), DDD uses the full source code paths.
  933.  
  934.    By default, DDD caches source files in memory.  This is convenient
  935. for remote debugging, since remote file access may be slow.  If you
  936. want to reduce memory usage, unset the `Edit => Preferences => Source
  937. => Cache source files' option.
  938.  
  939.    This is related to the following resource:
  940.  
  941.  - Resource: cacheSourceFiles (class CacheSourceFiles)
  942.      Whether to cache source files (`on', default) or not (`off').
  943.      Caching source files requires more memory, but makes DDD run
  944.      faster.
  945.  
  946. 
  947. File: ddd.info,  Node: Customizing File Filtering,  Prev: Customizing Source Lookup,  Up: Customizing Source
  948.  
  949. Customizing File Filtering
  950. --------------------------
  951.  
  952.    You can control whether DDD should filter files to be opened.
  953.  
  954.  - Resource: filterFiles (class FilterFiles)
  955.      If this is `on' (default), DDD filters files when opening
  956.      execution files, core dumps, or source files, such that the
  957.      selection shows only suitable files.  This requires that DDD opens
  958.      each file, which may take time.  If this is `off', DDD always
  959.      presents all available files.
  960.  
  961. 
  962. File: ddd.info,  Node: Stopping,  Next: Running,  Prev: Navigating,  Up: Top
  963.  
  964. Stopping the Program
  965. ********************
  966.  
  967.    The principal purposes of using a debugger are so that you can stop
  968. your program before it terminates; or so that, if your program runs into
  969. trouble, you can investigate and find out why.
  970.  
  971.    Inside DDD, your program may stop for any of several reasons, such
  972. as a signal, a breakpoint, or reaching a new line after a DDD command
  973. such as `Step'.  You may then examine and change variables, set new
  974. breakpoints or remove old ones, and then continue execution.
  975.  
  976.    The inferior debuggers supported by DDD support two mechanisms for
  977. stopping a program upon specific events:
  978.  
  979.    * A "breakpoint" makes your program stop whenever a certain point in
  980.      the program is reached.  For each breakpoint, you can add
  981.      conditions to control in finer detail whether your program stops.
  982.      Typically, breakpoints are set before running the program.
  983.  
  984.    * A "watchpoint" is a special breakpoint that stops your program when
  985.      the value of an expression changes.
  986.  
  987. * Menu:
  988.  
  989. * Breakpoints::                 Stop at a certain point.
  990. * Watchpoints::                 Stop at a certain condition.
  991. * Interrupting::                Stop manually.
  992. * Stopping X Programs::         Take care of grabbed pointers!
  993.  
  994. 
  995. File: ddd.info,  Node: Breakpoints,  Next: Watchpoints,  Up: Stopping
  996.  
  997. Breakpoints
  998. ===========
  999.  
  1000. * Menu:
  1001.  
  1002. * Setting Breakpoints::
  1003. * Deleting Breakpoints::
  1004. * Disabling Breakpoints::
  1005. * Temporary Breakpoints::
  1006. * Editing Breakpoint Properties::
  1007. * Breakpoint Conditions::
  1008. * Breakpoint Ignore Counts::
  1009. * Breakpoint Commands::
  1010. * Moving and Copying Breakpoints::
  1011. * Looking up Breakpoints::
  1012. * Editing all Breakpoints::
  1013. * Hardware-Assisted Breakpoints::
  1014.  
  1015. 
  1016. File: ddd.info,  Node: Setting Breakpoints,  Next: Deleting Breakpoints,  Up: Breakpoints
  1017.  
  1018. Setting Breakpoints
  1019. -------------------
  1020.  
  1021.    You can set breakpoints by location or by name.
  1022.  
  1023. Setting Breakpoints by Location
  1024. ...............................
  1025.  
  1026.    Breakpoints are set at a specific location in the program.
  1027.  
  1028.    If the source line is visible, click with _mouse button 1_ on the
  1029. left of the source line and then on the `Break' button.
  1030.  
  1031.    As a faster alternative, you can simply press _mouse button 3_ on
  1032. the left of the source line and select the `Set Breakpoint' item from
  1033. the line popup menu.
  1034.  
  1035.    As an even faster alternative, you can simply double-click on the
  1036. left of the source line to set a breakpoint.
  1037.  
  1038.    As yet another alternative, you can select `Source => Breakpoints'.
  1039. Click on the `Break' button and enter the location.
  1040.  
  1041.    (If you find this number of alternatives confusing, be aware that
  1042. DDD users fall into three categories, which must all be supported.
  1043. _Novice users_ explore DDD and may prefer to use one single mouse
  1044. button.  _Advanced users_ know how to use shortcuts and prefer popup
  1045. menus.  _Experienced users_ prefer the command line interface.)
  1046.  
  1047.    Breakpoints are indicated by a plain stop sign, or as `#N', where N
  1048. is the breakpoint number.  A greyed out stop sign (or `_N_') indicates
  1049. a disabled breakpoint.  A stop sign with a question mark (or `?N?')
  1050. indicates a conditional breakpoint or a breakpoint with an ignore count
  1051. set.
  1052.  
  1053.    If you set a breakpoint by mistake, use `Edit => Undo' to delete it
  1054. again.
  1055.  
  1056. Setting Breakpoints by Name
  1057. ...........................
  1058.  
  1059.    If the function name is visible, click with _mouse button 1_ on the
  1060. function name.  The function name is then copied to the argument field.
  1061. Click on the `Break' button to set a breakpoint there.
  1062.  
  1063.    As a shorter alternative, you can simply press _mouse button 3_ on
  1064. the function name and select the `Break at' item from the popup menu.
  1065.  
  1066.    As yet another alternative, you can click on `Break...' from the
  1067. Breakpoint editor (invoked through `Source => Breakpoints') and enter
  1068. the function name.
  1069.  
  1070. Setting Regexp Breakpoints
  1071. ..........................
  1072.  
  1073.    Using GDB, you can also set a breakpoint on all functions that match
  1074. a given string.  `Break => Set Breakpoints at Regexp ()' sets a
  1075. breakpoint on all functions whose name matches the _regular expression_
  1076. given in `()'.  Here are some examples:
  1077.  
  1078.    * To set a breakpoint on every function that starts with `Xm', set
  1079.      `()' to `^Xm'.
  1080.  
  1081.    * To set a breakpoint on every member of class `Date', set `()' to
  1082.      `^Date::'.
  1083.  
  1084.    * To set a breakpoint on every function whose name contains `_fun',
  1085.      set `()' to `_fun'.
  1086.  
  1087.    * To set a breakpoint on every function that ends in `_test', set
  1088.      `()' to `_test$'.
  1089.  
  1090. 
  1091. File: ddd.info,  Node: Deleting Breakpoints,  Next: Disabling Breakpoints,  Prev: Setting Breakpoints,  Up: Breakpoints
  1092.  
  1093. Deleting Breakpoints
  1094. --------------------
  1095.  
  1096.    To delete a visible breakpoint, click with _mouse button 1_ on the
  1097. breakpoint.  The breakpoint location is copied to the argument field.
  1098. Click on the `Clear' button to delete all breakpoints there.
  1099.  
  1100.    If the function name is visible, click with _mouse button 1_ on the
  1101. function name.  The function name is copied to the argument field.
  1102. Click on the `Clear' button to clear all breakpoints there.
  1103.  
  1104.    As a faster alternative, you can simply press _mouse button 3_ on
  1105. the breakpoint and select the `Delete Breakpoint' item from the popup
  1106. menu.
  1107.  
  1108.    As yet another alternative, you can select the breakpoint and click
  1109. on `Delete' in the Breakpoint editor (invoked through `Source =>
  1110. Breakpoints').
  1111.  
  1112.    As an even faster alternative, you can simply double-click on the
  1113. breakpoint while holding <Ctrl>.
  1114.  
  1115. 
  1116. File: ddd.info,  Node: Disabling Breakpoints,  Next: Temporary Breakpoints,  Prev: Deleting Breakpoints,  Up: Breakpoints
  1117.  
  1118. Disabling Breakpoints
  1119. ---------------------
  1120.  
  1121.    Rather than deleting a breakpoint or watchpoint, you might prefer to
  1122. "disable" it.  This makes the breakpoint inoperative as if it had been
  1123. deleted, but remembers the information on the breakpoint so that you
  1124. can "enable" it again later.(1)
  1125.  
  1126.    To disable a breakpoint, press _mouse button 3_ on the breakpoint
  1127. symbol and select the `Disable Breakpoint' item from the breakpoint
  1128. popup menu.  To enable it again, select `Enable Breakpoint'.
  1129.  
  1130.    As an alternative, you can select the breakpoint and click on
  1131. `Disable' or `Enable' in the Breakpoint editor (invoked through `Source
  1132. => Breakpoints'.
  1133.  
  1134.    Disabled breakpoints are indicated by a grey stop sign, or `_N_',
  1135. where N is the breakpoint number.
  1136.  
  1137.    The `Disable Breakpoint' item is also accessible via the `Clear'
  1138. button.  Just press and hold _mouse button 1_ on the button to get a
  1139. popup menu.
  1140.  
  1141.    ---------- Footnotes ----------
  1142.  
  1143.    (1) JDB does not support breakpoint disabling.
  1144.  
  1145. 
  1146. File: ddd.info,  Node: Temporary Breakpoints,  Next: Editing Breakpoint Properties,  Prev: Disabling Breakpoints,  Up: Breakpoints
  1147.  
  1148. Temporary Breakpoints
  1149. ---------------------
  1150.  
  1151.    A "temporary breakpoint" is immediately deleted as soon as it is
  1152. reached.(1)
  1153.  
  1154.    To set a temporary breakpoint, press _mouse button 3_ on the left of
  1155. the source line and select the `Set Temporary Breakpoint' item from the
  1156. popup menu.
  1157.  
  1158.    As a faster alternative, you can simply double-click on the left of
  1159. the source line while holding <Ctrl>.
  1160.  
  1161.    Temporary breakpoints are convenient to make the program continue up
  1162. to a specific location: just set the temporary breakpoint at this
  1163. location and continue execution.
  1164.  
  1165.    The `Continue Until Here' item from the popup menu sets a temporary
  1166. breakpoint on the left of the source line and immediately continues
  1167. execution.  Execution stops when the temporary breakpoint is reached.
  1168.  
  1169.    The `Set Temporary Breakpoint' and `Continue Until Here' items are
  1170. also accessible via the `Break' button.  Just press and hold _mouse
  1171. button 1_ on the button to get a popup menu.
  1172.  
  1173.    ---------- Footnotes ----------
  1174.  
  1175.    (1) JDB does not support temporary breakpoints.
  1176.  
  1177. 
  1178. File: ddd.info,  Node: Editing Breakpoint Properties,  Next: Breakpoint Conditions,  Prev: Temporary Breakpoints,  Up: Breakpoints
  1179.  
  1180. Editing Breakpoint Properties
  1181. -----------------------------
  1182.  
  1183.    You can change all properties of a breakpoint by pressing _mouse
  1184. button 3_ on the breakpoint symbol and select `Properties' from the
  1185. breakpoint popup menu.  This will pop up a dialog showing the current
  1186. properties of the selected breakpoint.
  1187.  
  1188.    As an even faster alternative, you can simply double-click on the
  1189. breakpoint.
  1190.  
  1191.    * Click on `Lookup' to move the cursor to the breakpoint's location.
  1192.  
  1193.    * Click on `Enable' to enable the breakpoint.
  1194.  
  1195.    * Click on `Disable' to disable the breakpoint.
  1196.  
  1197.    * Click on `Temp' to make the breakpoint temporary.(1)
  1198.  
  1199.    * Click on `Delete' to delete the breakpoint.
  1200.  
  1201.    ---------- Footnotes ----------
  1202.  
  1203.    (1) GDB has no way to make a temporary breakpoint non-temporary
  1204. again.
  1205.  
  1206. 
  1207. File: ddd.info,  Node: Breakpoint Conditions,  Next: Breakpoint Ignore Counts,  Prev: Editing Breakpoint Properties,  Up: Breakpoints
  1208.  
  1209. Breakpoint Conditions
  1210. ---------------------
  1211.  
  1212.    The simplest sort of breakpoint breaks every time your program
  1213. reaches a specified place.  You can also specify a "condition" for a
  1214. breakpoint.  A condition is just a Boolean expression in your
  1215. programming language.  A breakpoint with a condition evaluates the
  1216. expression each time your program reaches it, and your program stops
  1217. only if the condition is _true_.
  1218.  
  1219.    This is the converse of using assertions for program validation; in
  1220. that situation, you want to stop when the assertion is violated-that is,
  1221. when the condition is false.  In C, if you want to test an assertion
  1222. expressed by the condition ASSERTION, you should set the condition
  1223. `!ASSERTION' on the appropriate breakpoint.
  1224.  
  1225.    Break conditions can have side effects, and may even call functions
  1226. in your program.  This can be useful, for example, to activate functions
  1227. that log program progress, or to use your own print functions to format
  1228. special data structures. The effects are completely predictable unless
  1229. there is another enabled breakpoint at the same address.  (In that case,
  1230. DDD might see the other breakpoint first and stop your program without
  1231. checking the condition of this one.)
  1232.  
  1233.    Note that breakpoint commands are usually more convenient and
  1234. flexible for the purpose of performing side effects when a breakpoint
  1235. is reached.  *Note Breakpoint Commands::, for details.
  1236.  
  1237. 
  1238. File: ddd.info,  Node: Breakpoint Ignore Counts,  Next: Breakpoint Commands,  Prev: Breakpoint Conditions,  Up: Breakpoints
  1239.  
  1240. Breakpoint Ignore Counts
  1241. ------------------------
  1242.  
  1243.    A special case of a breakpoint condition is to stop only when the
  1244. breakpoint has been reached a certain number of times.  This is so
  1245. useful that there is a special way to do it, using the "ignore count"
  1246. of the breakpoint.  Every breakpoint has an ignore count, which is an
  1247. integer.  Most of the time, the ignore count is zero, and therefore has
  1248. no effect.  But if your program reaches a breakpoint whose ignore count
  1249. is positive, then instead of stopping, it just decrements the ignore
  1250. count by one and continues.  As a result, if the ignore count value is
  1251. N, the breakpoint does not stop the next N times your program reaches
  1252. it.
  1253.  
  1254.    In the field `Ignore Count' of the `Breakpoint Properties' panel,
  1255. you can specify the breakpoint ignore count.(1)
  1256.  
  1257.    If a breakpoint has a positive ignore count and a condition, the
  1258. condition is not checked.  Once the ignore count reaches zero, DDD
  1259. resumes checking the condition.
  1260.  
  1261.    ---------- Footnotes ----------
  1262.  
  1263.    (1) JDB, Perl and some DBX variants do not support breakpoint ignore
  1264. counts.
  1265.  
  1266. 
  1267. File: ddd.info,  Node: Breakpoint Commands,  Next: Moving and Copying Breakpoints,  Prev: Breakpoint Ignore Counts,  Up: Breakpoints
  1268.  
  1269. Breakpoint Commands
  1270. -------------------
  1271.  
  1272.    You can give any breakpoint (or watchpoint) a series of DDD commands
  1273. to execute when your program stops due to that breakpoint.  For
  1274. example, you might want to print the values of certain expressions, or
  1275. enable other breakpoints.(1)
  1276.  
  1277.    Using the `Commands' buttons of the `Breakpoint Properties' panel,
  1278. you can edit commands to be executed when the breakpoint is hit.
  1279.  
  1280.    To edit breakpoint commands, click on `Edit >>' and enter the
  1281. commands in the commands editor.  When done with editing, click on
  1282. `Edit <<' to close the commands editor.
  1283.  
  1284.    Using GDB, you can also "record" a command sequence to be executed.
  1285. To record a command sequence, follow these steps:
  1286.  
  1287.   1. Click on `Record' to begin the recording of the breakpoint
  1288.      commands.
  1289.  
  1290.   2. Now interact with DDD.  While recording, DDD does not execute
  1291.      commands, but simply records them to be executed when the
  1292.      breakpoint is hit.  The recorded debugger commands are shown in the
  1293.      debugger console.
  1294.  
  1295.   3. To stop the recording, click on `End' or enter `end' at the GDB
  1296.      prompt.  To "cancel" the recording, click on `Interrupt' or press
  1297.      <ESC>.
  1298.  
  1299.   4. You can edit the breakpoint commands just recorded using `Edit >>'.
  1300.  
  1301.    ---------- Footnotes ----------
  1302.  
  1303.    (1) JDB, PYDB, and some DBX variants do not support breakpoint
  1304. commands.
  1305.  
  1306. 
  1307. File: ddd.info,  Node: Moving and Copying Breakpoints,  Next: Looking up Breakpoints,  Prev: Breakpoint Commands,  Up: Breakpoints
  1308.  
  1309. Moving and Copying Breakpoints
  1310. ------------------------------
  1311.  
  1312.    To move a breakpoint to a different location, press _mouse button 1_
  1313. on the stop sign and drag it to the desired location.(1)  This is
  1314. equivalent to deleting the breakpoint at the old location and setting a
  1315. breakpoint at the new location.  The new breakpoint inherits all
  1316. properties of the old breakpoint, except the breakpoint number.
  1317.  
  1318.    To copy a breakpoint to a new location, press <Shift> while dragging.
  1319.  
  1320.    ---------- Footnotes ----------
  1321.  
  1322.    (1) When glyphs are disabled (*note Customizing Source::),
  1323. breakpoints cannot be dragged.  Delete and set breakpoints instead.
  1324.  
  1325. 
  1326. File: ddd.info,  Node: Looking up Breakpoints,  Next: Editing all Breakpoints,  Prev: Moving and Copying Breakpoints,  Up: Breakpoints
  1327.  
  1328. Looking up Breakpoints
  1329. ----------------------
  1330.  
  1331.    If you wish to lookup a specific breakpoint, select `Source =>
  1332. Breakpoints => Lookup'.  After selecting a breakpoint from the list and
  1333. clicking the `Lookup' button, the breakpoint location is displayed.
  1334.  
  1335.    As an alternative, you can enter `#N' in the argument field, where N
  1336. is the breakpoint number, and click on the `Lookup' button to find its
  1337. definition.
  1338.  
  1339. 
  1340. File: ddd.info,  Node: Editing all Breakpoints,  Next: Hardware-Assisted Breakpoints,  Prev: Looking up Breakpoints,  Up: Breakpoints
  1341.  
  1342. Editing all Breakpoints
  1343. -----------------------
  1344.  
  1345.    To view and edit all breakpoints at once, select `Source =>
  1346. Breakpoints'.  This will popup the "Breakpoint Editor" which displays
  1347. the state of all breakpoints.
  1348.  
  1349.    In the breakpoint editor, you can select individual breakpoints by
  1350. clicking on them.  Pressing <Ctrl> while clicking toggles the
  1351. selection.  To edit the properties of all selected breakpoints, click on
  1352. `Props'.
  1353.  
  1354.